=======

Features
--------

- Allowed using `dict` as an ordered type in ``setuptools.dist.check_requirements`` -- by :user:`Avasam` (4575)


Bugfixes
--------

- Ensured methods in ``setuptools.modified`` preferably raise a consistent
``distutils.errors.DistutilsError`` type
(except in the deprecated use case of ``SETUPTOOLS_USE_DISTUTILS=stdlib``)
-- by :user:`Avasam` (4567)
- Fix the ABI tag when building a wheel using the debug build of Python 3.13 on Windows. Previously, the ABI tag was missing the ``"d"`` flag. (4674)
- Fix clashes for ``optional-dependencies`` in ``pyproject.toml`` and
``extra_requires`` in ``setup.cfg/setup.py``.
As per PEP 621, ``optional-dependencies`` have to be honoured and dynamic
behaviour is not allowed. (4696)


Misc
----

- 4560

=======

Features
--------

- Made errors when parsing ``Distribution`` data more explicit about the expected type (``tuple[str, ...] | list[str]``) -- by :user:`Avasam` (4578)


Bugfixes
--------

- Fix a `TypeError` when a ``Distribution``'s old included attribute was a `tuple` -- by :user:`Avasam` (4578)
- Add workaround for ``bdist_wheel --dist-info-dir`` errors
when customisation does not inherit from setuptools. (4684)

=======

Bugfixes
--------

- Re-use pre-existing ``.dist-info`` dir when creating wheels via the build backend APIs (PEP 517) and the ``metadata_directory`` argument is passed -- by :user:`pelson`. (1825)
- Changed ``egg_info`` command to avoid adding an empty ``.egg-info`` directory
while iterating over entry-points.
This avoids triggering integration problems with ``importlib.metadata``/``importlib_metadata``
(reference: pypa/pyproject-hooks206). (4680)

=======

Features
--------

- Deprecated ``bdist_wheel.universal`` configuration. (4617)


Bugfixes
--------

- Removed reference to upload_docs module in entry points. (4650)

=======

Features
--------

- Declare also the dependencies used by distutils (adds jaraco.collections).


Deprecations and Removals
-------------------------

- Removed upload_docs command. (2971)
- Merge with pypa/distutils7283751. Removed the register and upload commands and the config module that backs them (pypa/distutils294). Removed the borland compiler. Replaced vendored dependencies with natural dependencies. Cygwin C compiler now gets compilers from sysconfig (pypa/distutils296). (4649)

=======

Bugfixes
--------

- Fix cross-platform compilation using ``distutils._msvccompiler.MSVCCompiler`` -- by :user:`saschanaz` and :user:`Avasam` (4648)

=======

Bugfixes
--------

- Fixed TypeError in sdist filelist processing by adding support for pathlib Paths for the build_base. (4615)
- Removed degraded and deprecated ``test_integration`` (easy_install) from the test suite. (4632)

=======

Bugfixes
--------

- Fixed TypeError in ``msvc.EnvironmentInfo.return_env`` when no runtime redistributables are installed. (1902)

=======

Features
--------

- Added support for defining ``ext-modules`` via ``pyproject.toml``
(**EXPERIMENTAL**, may change in future releases). (4568)


Bugfixes
--------

- Merge with pypa/distutils3dcdf8567, removing the duplicate vendored copy of packaging. (4622)
- Restored ``setuptools.msvc.Environmentinfo`` as it is used externally. (4625)

=======

Features
--------

- Changed the type of error raised by ``setuptools.command.easy_install.CommandSpec.from_param`` on unsupported argument from `AttributeError` to `TypeError` -- by :user:`Avasam` (4548)
- Added detection of ARM64 variant of MSVC -- by :user:`saschanaz` (4553)
- Made ``setuptools.package_index.Credential`` a `typing.NamedTuple` -- by :user:`Avasam` (4585)
- Reraise error from ``setuptools.command.easy_install.auto_chmod`` instead of nonsensical ``TypeError: 'Exception' object is not subscriptable`` -- by :user:`Avasam` (4593)
- Fully typed all collection attributes in ``pkg_resources`` -- by :user:`Avasam` (4598)
- Automatically exclude ``.tox|.nox|.venv`` directories from ``sdist``. (4603)


Deprecations and Removals
-------------------------

- Removed the monkeypatching of distutils._msvccompiler. Now all compiler logic is consolidated in distutils. (4600)
- Synced with pypa/distutils58fe058e4, including consolidating Visual Studio 2017 support (4600, pypa/distutils289), removal of deprecated legacy MSVC compiler modules (pypa/distutils287), suppressing of errors when the home directory is missing (pypa/distutils278), removal of wininst binaries (pypa/distutils282). (4606)


Misc
----

- 4592

=======

Bugfixes
--------

- Remove `abc.ABCMeta` metaclass from abstract classes. `pypa/setuptools4503 <https://github.com/pypa/setuptools/pull/4503>`_ had an unintended consequence of causing potential ``TypeError: metaclass conflict: the metaclass of a derived class must be a (non-strict) subclass of the metaclasses of all its bases`` -- by :user:`Avasam` (#4579)

=======

Features
--------

- Mark abstract base classes and methods with `abc.ABC` and `abc.abstractmethod` -- by :user:`Avasam` (4503)
- Changed the order of type checks in ``setuptools.command.easy_install.CommandSpec.from_param`` to support any `collections.abc.Iterable` of `str` param -- by :user:`Avasam` (4505)


Bugfixes
--------

- Prevent an error in ``bdist_wheel`` if ``compression`` is set to a `str` (even if valid) after finalizing options but before running the command. -- by :user:`Avasam` (4383)
- Raises an exception when ``py_limited_api`` is used in a build with
``Py_GIL_DISABLED``. This is currently not supported (python/cpython111506). (4420)
- Synced with pypa/distutils30b7331 including fix for modified check on empty sources (pypa/distutils284).


Deprecations and Removals
-------------------------

- ``setuptools`` is replacing the usages of :pypi:`ordered_set` with simple
instances of ``dict[Hashable, None]``. This is done to remove the extra
dependency and it is possible because since Python 3.7, ``dict`` maintain
insertion order. (4574)


Misc
----

- 4534, 4546, 4554, 4559, 4565

=======

Features
--------

- Merged with pypa/distutilsb7ee725f3 including: Support for Pathlike objects in data files and extensions (pypa/distutils272, pypa/distutils237), native support for C++ compilers (pypa/distuils228) and removed unused get_msvcr() (pypa/distutils274). (4538)

=======

Features
--------

- Restore the tests command and deprecate access to the module. (4519) (4520)

=======

Deprecations and Removals
-------------------------

- The test command has been removed. Users relying on 'setup.py test' will need to migrate to another test runner or pin setuptools before this version. (931)

=======

Features
--------

- Added return types to typed public functions -- by :user:`Avasam`

Marked `pkg_resources` as ``py.typed`` -- by :user:`Avasam` (4409)


Misc
----

- 4492

=======

Bugfixes
--------

- Removed lingering unused code around Distribution._patched_dist. (4489)

=======

Bugfixes
--------

- Reset the backports module when enabling vendored packages. (4476)

=======

Bugfixes
--------

- Include all vendored files in the sdist. (4480)

=======

Bugfixes
--------

- Restored package data that went missing in 71.0. This change also incidentally causes tests to be installed once again. (4475)

=======

Deprecations and Removals
-------------------------

- Now setuptools declares its own dependencies in the ``core`` extra. Dependencies are still vendored for bootstrapping purposes, but setuptools will prefer installed dependencies if present. The ``core`` extra is used for informational purposes and should *not* be declared in package metadata (e.g. ``build-requires``). Downstream packagers can de-vendor by simply removing the ``setuptools/_vendor`` directory. Since Setuptools now prefers installed dependencies, those installing to an environment with old, incompatible dependencies will not work. In that case, either uninstall the incompatible dependencies or upgrade them to satisfy those declared in ``core``. (2825)

=======

Features
--------

- Support for loading distutils from the standard library is now deprecated, including use of SETUPTOOLS_USE_DISTUTILS=stdlib and importing distutils before importing setuptools. (4137)


Bugfixes
--------

- Bugfix for building Cython extension on Windows (pypa/distutils268).

=======

Features
--------

- Updated distutils including significant changes to support Cygwin and mingw compilers. (4444)


Bugfixes
--------

- Fix distribution name normalisation (:pep:`625`) for valid versions that are
not canonical (e.g. ``1.0-2``). (4434)

=======

Misc
----

- 4429

=======

Features
--------

- Adopted the ``bdist_wheel`` command from the ``wheel`` project -- by :user:`agronholm` (1386)
- Improve error message when ``pkg_resources.ZipProvider`` tries to extract resources with a missing Egg -- by :user:`Avasam`

Added variables and parameter type annotations to ``pkg_resources`` to be nearly on par with typeshed.\* -- by :user:`Avasam`
\* Excluding ``TypeVar`` and ``overload``. Return types are currently inferred. (4246)
- Migrated Setuptools' own config to pyproject.toml (4310)


Bugfixes
--------

- Prevent a ``TypeError: 'NoneType' object is not callable`` when ``shutil_rmtree`` is called without an ``onexc`` parameter on Python<=3.11 -- by :user:`Avasam` (4382)
- Replace use of mktemp with can_symlink from the stdlib test suite. (4403)
- Improvement for ``attr:`` directives in configuration to handle
more edge cases related to complex ``package_dir``. (4405)
- Fix accidental implicit string concatenation. (4411)


Misc
----

- 4365, 4422

=======

Features
--------

- Emit a warning when ``[tools.setuptools]`` is present in ``pyproject.toml`` and will be ignored. -- by :user:`SnoopJ` (4150)
- Improved `AttributeError` error message if ``pkg_resources.EntryPoint.require`` is called without extras or distribution
Gracefully "do nothing" when trying to activate a ``pkg_resources.Distribution`` with a `None` location, rather than raising a `TypeError`
-- by :user:`Avasam` (4262)
- Typed the dynamically defined variables from `pkg_resources` -- by :user:`Avasam` (4267)
- Modernized and refactored VCS handling in package_index. (4332)


Bugfixes
--------

- In install command, use super to call the superclass methods. Avoids race conditions when monkeypatching from _distutils_system_mod occurs late. (4136)
- Fix finder template for lenient editable installs of implicit nested namespaces
constructed by using ``package_dir`` to reorganise directory structure. (4278)
- Fix an error with `UnicodeDecodeError` handling in ``pkg_resources`` when trying to read files in UTF-8 with a fallback -- by :user:`Avasam` (4348)


Improved Documentation
----------------------

- Uses RST substitution to put badges in 1 line. (4312)


Deprecations and Removals
-------------------------

- Further adoption of UTF-8 in ``setuptools``.
This change regards mostly files produced and consumed during the build process
(e.g. metadata files, script wrappers, automatically updated config files, etc..)
Although precautions were taken to minimize disruptions, some edge cases might
be subject to backwards incompatibility.

Support for ``"locale"`` encoding is now **deprecated**. (4309)
- Remove ``setuptools.convert_path`` after long deprecation period.
This function was never defined by ``setuptools`` itself, but rather a
side-effect of an import for internal usage. (4322)
- Remove fallback for customisations of ``distutils``' ``build.sub_command`` after long
deprecated period.
Users are advised to import ``build`` directly from ``setuptools.command.build``. (4322)
- Removed ``typing_extensions`` from vendored dependencies -- by :user:`Avasam` (4324)
- Remove deprecated ``setuptools.dep_util``.
The provided alternative is ``setuptools.modified``. (4360)


Misc
----

- 4255, 4280, 4282, 4308, 4348

=======

No significant changes.

=======

Features
--------

- Refresh unpinned vendored dependencies. (4253)
- Updated vendored packaging to version 24.0. (4301)

=======

Bugfixes
--------

- Merged bugfix for pypa/distutils246.

=======

No significant changes.

=======

Features
--------

- Merged with pypa/distutils55982565e, including interoperability improvements for rfc822_escape (pypa/distutils213), dynamic resolution of config_h_filename for Python 3.13 compatibility (pypa/distutils219), added support for the z/OS compiler (pypa/distutils216), modernized compiler options in unixcompiler (pypa/distutils214), fixed accumulating flags bug after compile/link (pypa/distutils207), fixed enconding warnings (pypa/distutils236), and general quality improvements (pypa/distutils234). (4298)

=======

Bugfixes
--------

- Remove attempt to canonicalize the version. It's already canonical enough. (4302)

=======

Features
--------

- Support PEP 625 by canonicalizing package name and version in filenames
per
`the spec <https://packaging.python.org/en/latest/specifications/source-distribution-format/#source-distribution-file-name>`_.
Projects whose names contain uppercase characters, dashes, or periods will
now see their sdist names normalized to match the standard and the format
previously seen in wheels. For example:

- ``zope.interface`` -> ``zope_interface``
- ``CherryPy`` -> ``cherrypy``
- ``foo-bar_baz`` -> ``foo_bar_baz``

Projects are encouraged to adopt this change to align with standards and
other backend build systems. (3593)

=======

Features
--------

- Explicitly use ``encoding="locale"`` for ``.pth`` files whenever possible,
to  reduce ``EncodingWarnings``.
This avoid errors with UTF-8 (see discussion in python/cpython77102). (4265)


Bugfixes
--------

- Clarify some `pkg_resources` methods return `bytes`, not `str`. Also return an empty `bytes` in ``EmptyProvider._get`` -- by :user:`Avasam` (4243)
- Return an empty `list` by default in ``pkg_resources.ResourceManager.cleanup_resources`` -- by :user:`Avasam` (4244)
- Made ``pkg_resoursces.NullProvider``'s ``has_metadata`` and ``metadata_isdir`` methods return actual booleans like all other Providers. -- by :user:`Avasam` (4254)


Misc
----

- 4237, 4238, 4241, 4260, 4261, 4263

=======

Bugfixes
--------

- Fix argument order of ``--config-settings["--build-option"]`` arguments.
This was broken by <https://github.com/pypa/setuptools/pull/4079>`. (#4217)


Misc
----

- 4231

=======

Features
--------

- Updated and removed obsolete Python < 3.8 code and comments. -- by :user:`Avasam` (4096)
- Updated `pkg_resources` to use stdlib `importlib.machinery` instead of ``importlib_machinery`` -- by :user:`Avasam` (4097)


Bugfixes
--------

- In tests, rely on pytest-home for reusable fixture. (4072)
- Explicitely marked as ``Protocol`` and fixed missing ``self`` argument in interfaces ``pkg_resources.IMetadataProvider`` and ``pkg_resources.IResourceProvider`` -- by :user:`Avasam` (4144)
- Restored expectation that egg-link files would be named with dash separators for compatibility with pip prior to version 24. (4167)


Improved Documentation
----------------------

- Updated documentation referencing obsolete Python 3.7 code. -- by :user:`Avasam` (4096)
- Changed ``versionadded`` for "Type information included by default" feature from ``v68.3.0`` to ``v69.0.0`` -- by :user:`Avasam` (4182)
- Described the auto-generated files -- by :user:`VladimirFokow` (4198)
- Updated "Quickstart" to describe the current status of ``setup.cfg`` and ``pyproject.toml`` -- by :user:`VladimirFokow` (4200)

=======

Bugfixes
--------

- Retain valid names with underscores in egg_info.

=======

Bugfixes
--------

- Added missing estimated date for removing ``setuptools.dep_util`` (deprecated in v69.0.0). (4131)

=======

Bugfixes
--------

- Fixed imports of ``setuptools.dep_util.newer_group``.
A deprecation warning is issued instead of a hard failure. (4126)

=======

Features
--------

- Include type information (``py.typed``, ``*.pyi``) by default (3136) -- by :user:`Danie-1`,
**EXPERIMENTAL**. (3136)
- Exported ``distutils.dep_util`` and ``setuptools.dep_util`` through ``setuptools.modified`` -- by :user:`Avasam` (4069)
- Merged with pypa/distutils7a04cbda0fc714.


Bugfixes
--------

- Replaced hardcoded numeric values with :obj:`dis.opmap`,
fixing problem with 3.13.0a1. (4094)


Deprecations and Removals
-------------------------

- Configuring project ``version`` and ``egg_info.tag_*`` in such a way that
results in invalid version strings (according to :pep:`440`) is no longer permitted. (4066)
- Removed deprecated ``egg_base`` option from ``dist_info``.
Note that the ``dist_info`` command is considered internal to the way
``setuptools`` build backend works and not intended for
public usage. (4066)
- The parsing of the deprecated ``metadata.license_file`` and
``metadata.requires`` fields in ``setup.cfg`` is no longer supported.
Users are expected to move to ``metadata.license_files`` and
``options.install_requires`` (respectively). (4066)
- Passing ``config_settings`` to ``setuptools.build_meta`` with
deprecated values for ``--global-option`` is no longer allowed. (4066)
- Removed deprecated ``namespace-packages`` from ``pyproject.toml``.
Users are asked to use
:doc:`implicit namespace packages <PyPUG:guides/packaging-namespace-packages>`
(as defined in :pep:`420`). (4066)
- Added strict enforcement for ``project.dynamic`` in ``pyproject.toml``.
This removes the transitional ability of users configuring certain parameters
via ``setup.py`` without making the necessary changes to ``pyproject.toml``
(as mandated by :pep:`621`). (4066)
- Removed handling of ``--config-settings["--build-option"]`` in ``setuptools.build_meta``
from build-backend API hooks *other than* ``build_wheel``.
This was motivate by `errors caused when passing this option
<https://github.com/pypa/setuptools/issues/2491#issuecomment-1742859314>`_. (4079)

=======

Bugfixes
--------

- Improve backwards compatibility with deprecated CLI practices. (4048)

=======

Bugfixes
--------

- Avoid using caching attributes in ``Distribution.metadata`` for requirements.
This is done for backwards compatibility with customizations that attempt to
modify ``install_requires`` or ``extras_require`` at a late point (still not
recommended). (4043)


Misc
----

- 4045

=======

Features
--------

- Rework how ``setuptools`` internally handles ``dependencies/install_requires``
and ``optional-dependencies/extras_require``. (3903)
- Improve the generated ``PKG-INFO`` files, by adding ``Requires-Dist`` fields.
Previously, these fields would be omitted in favour of a non-standard
``*.egg-info/requires.txt`` file (which is still generated for the time being). (3904)
- Improve atomicity when writing ``PKG-INFO`` files to avoid race
conditions with ``importlib.metadata``. (3904)


Bugfixes
--------

- Fix the name given to the ``*-nspkg.pth`` files in editable installs,
ensuring they are unique per distribution. (4041)
- Workaround some limitations on ``pkg_resources``-style legacy namespaces in
the meta path finder for editable installations. (4041)


Misc
----

- 4023, 4027, 4027

=======

Misc
----

- 4022, 4022

=======

Bugfixes
--------

- Fix editable install finder handling of nested packages, by only handling 1
level of nesting and relying on ``importlib.machinery`` to find the remaining
modules based on the parent package path. (4020)

=======

Features
--------

- Removed code referencing bdist_wininst in install_scripts. (3525)
- Promote ``pyproject.toml``'s ``[tool.setuptools]`` out of beta.
Note that some fields are still considered deprecated and/or obsolete,
and these might be removed in future versions (i.e., there is no guarantee
for long term support and backward compatibility on those fields). (3962)
- Automatically add files listed in ``Extension.depends`` to sdists,
as long as they are contained in the project directory -- by :user:`RuRo` (4000)
- Require Python 3.8 or later.


Bugfixes
--------

- Made imports in editable installs case-sensitive on case-insensitive filesystems -- by :user:`aganders3` (3995)
- Use default encoding to create ``.pth`` files with ``editable_wheel``. (4009)
- Detects (and complain about) ``scripts`` and ``gui-scripts`` set via ``setup.py``
when ``pyproject.toml`` does not include them in ``dynamic``. (4012)


Misc
----

- 3833, 3960, 4001, 4007

=======


Breaking Changes
----------------
* 3948: Removed verification for existing ``depends.txt`` file (deprecated since v0.5a4).
* 3948: Remove autofixing of broken ``.egg-info`` directories containing the ``-``
character in their base name (without suffix).
They should no longer be produced by sufficiently new versions of ``setuptools``
(warning introduced in 2005).
* 3948: Remove deprecated APIs in ``easy_install``: ``get_script_args``,
``get_script_header`` and ``get_writer``.
The direct usage of ``easy_install`` has been deprecated since v58.3.0,
and the warnings regarding these APIs predate that version.
* 3948: Removed ``egg_info.get_pkg_info_revision`` (deprecated since 2015).
* 3948: Removed ``setuptools.dist._get_unpatched`` (deprecated since 2016)
* 3948: Removed support for SVN in ``setuptools.package_index`` (deprecated since 2018).
* 3948: Removed support for invalid ``pyproject.toml`` files.
During the implementation of PEP 621, it was identified that some users were
producing invalid files. As a transitional measure, the validation was relaxed
for a few use cases. The grace period, however, came to an end.

Changes
-------
* 3760: Added symlink support to launcher for installed executables -- by :user:`eugene-sevostianov-sc`
* 3926: Updated vendored ``packaging`` version from 23.0 to 23.1 -- by :user:`MetRonnie`
* 3950: Implemented workaround for old versions of ``vswhere``, which miss the
``-requiresAny`` parameter, such as the ones distributed together with Visual Studio 2017 < 15.6.
* 3952: Changed ``DistutilsMetaFinder`` to skip ``spec_for_pip`` on Python >= 3.12.
* 3952: Removed ``_distutils_hack.remove_shim`` on Python >= 3.12
(since ``distutils`` was removed from the standard library,
``DistutilsMetaFinder`` cannot be disabled on Python >= 3.12).

Misc
----
* 3920: Add a link to deprecation warning in ``pkg_resources`` and improve
``stacklevel`` for better visibility.

=======


Changes
-------
* 3128: In deprecated easy_install, reload and merge the pth file before saving.

Misc
----
* 3915: Adequate tests to the latest changes in ``virtualenv`` for Python 3.12.

=======


Misc
----
* 3902: Fixed wrong URLs used in warnings and logs.

=======


Misc
----
* 3898: Fixes setuptools.dist:invalid_unless_false when value is false don't raise error -- by :user:`jammarher`

=======


Changes
-------
* 3849: Overhaul warning system for better visibility.

Documentation changes
---------------------
* 3859: Added a note about historical presence of ``wheel``
in ``build-system.requires``, in ``pyproject.toml``.
* 3893: Improved the documentation example regarding making a thin :pep:`517` in-tree
backend wrapper of ``setuptools.build_meta`` that is future-proof and supports
:pep:`660` hook too -- by :user:`webknjaz`.

Misc
----
* 3884: Add a ``stacklevel`` parameter to ``warnings.warn()`` to provide more information to the user.
-- by :user:`cclauss`

=======


Misc
----
* 3865: Fixed ``_WouldIgnoreField`` warnings for ``scripts`` and ``gui_scripts``,
when ``entry-points`` is not listed in dynamic.
* 3875: Update code generated by ``validate-pyproject`` to use v0.12.2.
This should fix default license patterns when ``pyproject.toml`` is used.

=======


Changes
-------
* 3804: Added caching for supported wheel tags.
* 3846: Added pruning heuristics to ``PackageFinder`` based on ``exclude``.

=======


Misc
----
* 3836: Fixed interaction between ``setuptools``' package auto-discovery and
auto-generated ``htmlcov`` files.

Previously, the ``htmlcov`` name was ignored when searching for single-file
modules, however the correct behaviour is to ignore it when searching for
packages (since it is supposed to be a directory, see `coverage config`_)
-- by :user:`yukihiko-shinoda`.

.. _coverage config: https://coverage.readthedocs.io/en/stable/config.html#html-directory
* 3838: Improved error messages for ``pyproject.toml`` validations.
* 3839: Fixed ``pkg_resources`` errors caused when parsing metadata of packages that
are already installed but do not conform with PEP 440.

=======


Changes
-------
* 3843: Although pkg_resources has been discouraged for use, some projects still consider pkg_resources viable for usage. This change makes it clear that pkg_resources should not be used, emitting a DeprecationWarning when imported.

=======


Changes
-------
* 3832: Update vendored ``importlib-metadata`` (to 6.0.0) and
``importlib-resources`` (to 5.10.2)

=======


Misc
----
* 3820: Restore quoted ``include`` argument to ``has_function``.

=======


Misc
----
* 3827: Improve deprecation warning message on ``pkg_resources.declare_namespace``
to display package name.

=======


Misc
----
* 3823: Fixes ``egg_info`` code path triggered during integration with ``pip``.

=======


Deprecations
------------
* 3434: Added deprecation warning for ``pkg_resources.declare_namespace``.
Users that wish to implement namespace packages, are recommended to follow the
practice described in PEP 420 and omit the ``__init__.py`` file entirely.

Changes
-------
* 3792: Reduced usage of ``pkg_resources`` in ``setuptools`` via internal
restructuring and refactoring.

Misc
----
* 3822: Added debugging tips for "editable mode" and update related docs.
Instead of using a custom exception to display the help message to the user,
``setuptools`` will now use a warning and re-raise the original exception.
* 3822: Added clarification about ``editable_wheel`` and ``dist_info`` CLI commands:
they should not be called directly with ``python setup.py ...``.
Instead they are reserved for internal use of ``setuptools`` (effectively as "private" commands).
Users are recommended to rely on build backend APIs (:pep:`517` and :pep:`660`)
exposed by ``setuptools.build_meta``.

=======


Changes
-------
* 3809: Merge with distutils8c3c3d29, including fix for ``sysconfig.get_python_inc()`` (pypa/distutils178), fix for segfault on MinGW (pypa/distutils196), and better ``has_function`` support (pypa/distutils195, 3648).

=======


Changes
-------
* 3795: Ensured that ``__file__`` is an absolute path when executing ``setup.py`` as
part of ``setuptools.build_meta``.

Misc
----
* 3798: Updated validations for ``pyproject.toml`` using ``validate-pyproject==0.12.1``
to allow stub packages (:pep:`561`) to be listed in ``tool.setuptools.packages``
and ``tool.setuptools.package-dir``.

=======


Breaking Changes
----------------
* 3741: Removed patching of ``distutils._msvccompiler.gen_lib_options``
for compatibility with Numpy < 1.11.2 -- by :user:`mgorny`
* 3790: Bump vendored version of :pypi:`packaging` to 23.0
(:pypi:`pyparsing` is no longer required and was removed).
As a consequence, users will experience a more strict parsing of requirements.
Specifications that don't comply with :pep:`440` and :pep:`508` will result
in build errors.

=======


Misc
----
* 3782: Fixed problem with ``file`` directive in ``tool.setuptools.dynamic``
(``pyproject.toml``) when value is a simple string instead of list.

=======


Changes
-------
* 3685: Fix improper usage of deprecated/removed ``pkgutil`` APIs in Python 3.12+.
* 3779: Files referenced by ``file:`` in ``setup.cfg`` and by ``project.readme.file``,
``project.license.file`` or ``tool.setuptools.dynamic.*.file`` in
``pyproject.toml`` are now automatically included in the generated sdists.

Misc
----
* 3776: Added note about using the ``--pep-517`` flag with ``pip`` to workaround
``InvalidVersion`` errors for packages that are already installed in the system.

=======


Breaking Changes
----------------
* 2497: Support for PEP 440 non-conforming versions has been removed. Environments containing packages with non-conforming versions may fail or the packages may not be recognized.

Changes
-------
* 3769: Replace 'appdirs' with 'platformdirs'.

=======


Changes
-------
* 3594: Added ``htmlcov`` to FlatLayoutModuleFinder.DEFAULT_EXCLUDE -- by :user:`demianbrecht`
* 3667: Added a human-readable error description when ``.egg-info`` directory is not writeable -- by :user:`droodev`

Misc
----
* 3713: Fixed incomplete ``getattr`` statement that caused problems when accessing
undefined attribute.

=======


Misc
----
* 3709: Fix condition to patch ``distutils.dist.log`` to only apply when using
``distutils`` from the stdlib.

=======

No significant changes.

=======


Documentation changes
---------------------
* 3689: Documented that ``distutils.cfg`` might be ignored unless
``SETUPTOOLS_USE_DISTUTILS=stdlib``.

Misc
----
* 3678: Improve clib builds reproducibility by sorting sources -- by :user:`danigm`
* 3684: Improved exception/traceback when invalid entry-points are specified.
* 3690: Fixed logging errors: 'underlying buffer has been detached' (issue 1631).
* 3693: Merge pypa/distutils3e9d47e with compatibility fix for distutils.log.Log.
* 3695, 3697, 3698, 3699: Changed minor text details (spelling, spaces ...)
* 3696: Removed unnecessary ``coding: utf-8`` annotations
* 3704: Fixed temporary build directories interference with auto-discovery.

=======


Changes
-------
* 3674: Sync with pypa/distutilse0787fa, including pypa/distutils183 updating distutils to use the Python logging framework.

=======


Misc
----
* 3638: Drop a test dependency on the ``mock`` package, always use :external+python:py:mod:`unittest.mock` -- by :user:`hroncok`
* 3659: Fixed REDoS vector in package_index -- by :user:`SCH227`